docs(adr): propose ADR-0010 and ADR-0011 — the two halves of offline browse - #53

…ay mark (#57)

Every web play was landing with a completion ratio of almost exactly 0.5,
whatever the listener actually heard.

`usePlayTracking` delivered the play the moment listening crossed
`min(duration / 2, 4 min)` and sent `completion_ratio` as measured *at that
instant*. Nothing revised it afterwards, so the figure recorded when someone
heard a track once through and when they heard half of it were the same number.

Measured on the live database, 2026-08-01: **289 of 357 completed events sit in
the 0.5–0.6 bucket**, while rows from the native client — which reports at the end
— correctly read 0.95–1.00. Sample rows are exact: 166.0/331.4, 124.3/248.6,
120.6/241.0.

This matters because of what the data is for. ADR-0004 exists so ADR-0005's
recommender has a taste signal that can only accumulate in wall-clock time, and
completion is that signal. A constant carries none of it, so the month of data
`familiar` #53 is parked waiting for would have been a month of noise — and the
error is invisible in aggregate, because 0.5 is a thoroughly plausible average.

**Nothing changes about which plays count.** The early delivery only decided
*when*: a play past 30s but short of the half mark was already reported on track
change, by the same rule that now reports all of them. The Last.fm half/4-minute
threshold turned out to gate nothing, which is why it is gone rather than moved.

Two things that came with it:

- **A page-hide flush**, because the early delivery was quietly buying durability:
  close the tab mid-track and the play still counted, since it had already been
  sent. Reporting at the end would have dropped that silently. Restored on
  `pagehide` and `visibilitychange`, with the ratio actually heard. Best effort and
  described as such — a browser tearing down a page owes the request nothing.
- **The ratio is clamped.** Played time accumulates from the engine's clock while
  the duration is track metadata, so a looping or mis-tagged track could send 1.1.
  The server clamps as well, but agreeing with the native client — which has always
  clamped — beats leaving every stored figure a question about which end did it.

Tests: the three that asserted mid-playback delivery now assert delivery on track
change, and two were added — one pinning the ratio of a track heard nearly to the
end, one covering the page-hide path and that it cannot double-report. 940 pass.


Claude-Session: https://claude.ai/code/session_014P9p2fvFnyiywBxGkv4gfW

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

…ruction (#80)

Phase 1. Three decisions wait on ADR-0004's data — its own completion-ratio
threshold, ADR-0005's RADIO weights, and #53 — and the data does not start where
everyone assumed.

Until #57 the web client delivered a play the moment listening crossed
`min(duration / 2, 4 min)` and sent `completion_ratio` as measured at that
instant, never revising it. Verified again on the live database on 2026-08-02, by
day and context: **795 of 823 rows predate the fix**, and every context before
2026-08-01 shows completions averaging 0.42–0.50 — including `library`, because
the web derives context from the queue source and sends `library` for a library
queue exactly as the native app does. From 2026-08-01 the same context reads
0.972 and 1.000, with skips at ≤0.1.

So the clock restarted on 2026-08-01, not 2026-07-27: a month of trustworthy data
lands around 2026-09-01.

`FEEDBACK_TRUSTWORTHY_SINCE` and `trustworthy_feedback_only` make the boundary one
call away instead of a matter of discipline. A date, not a client filter, because
`play_events` records no client and `context` does not stand in for one — the good
native rows cannot be separated from the bad web rows beside them, and selecting
on the ratio would be circular.

Excluded rather than deleted, for a reason the investigation turned up: the damage
is not limited to the ratio. A track abandoned at 55% was recorded as a completion
at ~0.5 rather than as a skip, so `outcome` is unreliable before the cutoff and
skips are *under*-counted. What survives is that `skipped` and `rejected` rows
describe real abandonments. `ambient._negative_signal` counts exactly those two
over a rolling 90-day window — so **the live recommender was never poisoned**, it
has been running on a slightly weak negative signal that heals around 2026-10-30.

ADR-0005 also gains the `Implementation:` block it never had, which is why it
looked unbuilt in a survey while `RADIO` had been shipping for weeks.

Two follow-ups recorded: a `client` column, cheap now and worthless retroactively,
which is the only thing that would have made this separable; and that whether the
web still reports at all is unverified — every post-cutoff row carries the context
the native app hardcodes.


Claude-Session: https://claude.ai/code/session_014P9p2fvFnyiywBxGkv4gfW

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

CLAUDE.md loads into context every session, so a stale "what remains" is not a
tidy-up — it is a wrong instruction delivered on every turn. Three of them:

- ADR-0017's paragraph said the `WKWebView`, the message handler and the native
  unavailable state were still to build. They shipped in `familiar-apple` #43,
  and #53 brought the surface to the phone.
- ADR-0018's said "`0018` ships without Discover if `0019` is not accepted".
  Both are accepted and shipped.
- ADR-0022's said accepting it makes #76 reversible via a third bridge message.
  It did not go that way: `/library/discover/prompts` was already generated, so
  Listening Ideas came back natively and **the bridge stays at two messages**.
  That sentence would have steered the next session into building the thing we
  deliberately did not build, which is the worst kind of stale.

ADR-0017's own Implementation block carried the same claim — an accepted ADR is a
living record, and rule 6 protects the Decision, not the record of what shipped.
It now also lists the three defects that surface has produced, all one shape: an
affordance whose destination is not mounted, failing silently.

ADR-0022 gains its Implementation block: what shipped, the three places the server
did not match its documentation, and the empty-line SSE bug the ADR's own recorded
tradeoff predicted.

Also: the Music Map ordering note is spent, so it now records that the map's
interaction is still half-wired — the footer advertises scroll-to-zoom that was
never implemented, `zoomed(by:toward:)` is reachable only through `stepped()`, and
the drag gesture competes with click-to-focus. Verified against the source, not
from memory.

Key Files gains rows for the web chat and the embedded surface, neither of which
had a pointer.

Every PR number, path and claim re-checked (rule 4). `useChatAvailability.ts` was
dropped from Key Files because it exists only in the open #78, and the two open
PRs are marked as open rather than described as shipped.


Claude-Session: https://claude.ai/code/session_014P9p2fvFnyiywBxGkv4gfW

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>